Skip to content

docs: soften OIDC caveat, document workflow-perms autoflip#1

Merged
topcoder1 merged 2 commits into
mainfrom
docs/readme-polish
Apr 30, 2026
Merged

docs: soften OIDC caveat, document workflow-perms autoflip#1
topcoder1 merged 2 commits into
mainfrom
docs/readme-polish

Conversation

@topcoder1
Copy link
Copy Markdown
Owner

README polish based on canary on topcoder1/webcrawl PR #95:

  • Document that install-pr-review.sh auto-flips target repo workflow permissions to write (no longer a manual pre-step).
  • Soften the 'Claude Review check will fail on install PR' caveat to 'may fail; in practice often passes' — webcrawl PR #95 passed cleanly.
  • Note that install-pr-review.sh creates a ruleset by default (and how to skip).

@topcoder1 topcoder1 enabled auto-merge (squash) April 30, 2026 17:55
@topcoder1 topcoder1 merged commit 6d1d001 into main Apr 30, 2026
topcoder1 added a commit that referenced this pull request Apr 30, 2026
Match the new template stub from dotclaude#5. Without this, a docs-only
PR on this repo (e.g. README polish) gets paths-ignored, the required
'review / Claude Review' check never reports, and the PR is permanently
BLOCKED. Already happened once on PR #1.
topcoder1 added a commit that referenced this pull request May 13, 2026
## Problem

The seed-mode design self-committed the seeded value back to the install
PR's branch via `GITHUB_TOKEN`. This hits a documented GitHub
limitation: **`GITHUB_TOKEN` pushes do NOT re-trigger pull_request
workflows**. The self-commit creates a new HEAD SHA with no check runs
reported on it — the PR is permanently \"blocked\" without manual `gh pr
close + reopen` and an empty user-attributed push.

Caught on the first real-world install (whois-api-llc/wxa-jake-ai#389) —
required close+reopen + an empty user push to unblock. Doesn't scale to
6+ remaining repos.

## New design

**Two-PR flow:**

1. **Install PR** ships `.coverage-floor` with `current=0` (seed marker)
+ caller workflow.
2. On `pull_request` with `current=0`: PASS. Post comment naming
proposed floor. **No self-commit.**
3. Install PR auto-merges naturally (one HEAD SHA, one check set).
4. After merge, `push:main` with `current=0` measures coverage and
**opens a follow-up PR** `chore(coverage): seed floor at X.X%` with the
seeded `.coverage-floor`.
5. Follow-up PR is 1-file-change, labeled `coverage-floor-seed`,
safe-paths-automerge eligible — auto-merges.
6. After follow-up merges, future PRs run in enforce mode.

## Properties

- No GITHUB_TOKEN re-trigger problem — each push gets its own workflow
run; seed PR is a normal PR with its own checks
- Two-PR flow keeps each PR minimal (workflow file + .coverage-floor in
#1; just .coverage-floor in #2)
- Loop-prevention guard preserved (refuse to seed below `seed_minimum`)
- Idempotent: skip if a `coverage-floor-seed` PR is already open
- Auto-creates the `coverage-floor-seed` label on first run

## Self-test (this repo)

ci-workflows itself stays in enforce mode — `.coverage-floor` here has
`current=99.0` against ~100% selftest coverage. The new seed path only
fires when `current==0`, so no behavior change on this PR's self-test.

## Companion changes (next PRs)

- dotclaude installer (`install-coverage-floor.sh`): docs update —
install PR is now passive, expect a follow-up seed PR.

## Auto-merge rationale

Workflow file change in ci-workflows — risk:blocked, manual click
required (same as #50#54).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant